Inside Macintosh: QuickDraw GX Graphics /

Chapter 4 - Geometric Operations / Geometric Operations Reference

Functions / Finding Geometric Information About Shapes

GXShapeLengthToPoint

You can use the GXShapeLengthToPoint function to determine the point that falls at a certain distance along a contour of a shape.

gxPoint *GXShapeLengthToPoint(gxShape target, long index, 
                              Fixed length, gxPoint *location, 
                              gxPoint *tangent);

target

A reference to the shape containing the contour you want to examine.

index

The number of the contour within the shape. You may specify a value of 0 for this parameter to indicate that the function should start measuring at the beginning of the first contour and continue through all contours.

length

The distance along the specified contour.

location

A pointer to a gxPoint structure. On return, this structure contains the point that lies along the contour at the specified distance.

tangent

A pointer to a gxPoint structure. On return, this structure contains a point that specifies a tangent vector representing the slope of the contour at the specified distance.

function result

The point that lies along the contour at the specified distance. (This value
is the same as the value returned in the location parameter.)

DESCRIPTION

The GXShapeLengthToPoint function returns the location of the point that lies at the distance specified by the length parameter along the contour specified by the index parameter of the target shape.

If you provide a pointer for the tangent parameter that is not nil, this function returns the slope of the specified contour at that point, in the form of a tangent vector. (The tangent vector implicitly starts at point (0.0, 0.0) and ends at the point indicated by the returned tangent parameter.)

This function measures the contour length as defined in the shape's geometry; it does not consider transformations to the shape made by the shape's transform.

If the target shape has the noFill shape fill, this function posts the error shape_fill_not_allowed.

If the target shape is an empty shape or a full shape, this function posts the warning shape_does_not_have_length.

If you provide a target shape that is not one of the geometric shape types, this function performs the actions described in the following table:

Shape type	Action taken
bitmap	Posts the warning shape_does_not_have_length
picture	Posts the warning shape_does_not_have_length
text	Posts the warning shape_does_not_have_length
glyph	Posts the warning shape_does_not_have_length
layout	Posts the warning shape_does_not_have_length

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
length_is_less_than_zero	(debugging version)
parameter_is_nil	(debugging version)
shape_fill_not_allowed	(debugging version)
Warnings
contour_out_of_range
length_out_of_range
shape_does_not_have_length	(debugging version)
unable_to_traverse_open_contour_that_starts_or_ends_off_the_curve
	(debugging version)

SEE ALSO

For an example using this function, see "Finding the Point at a Certain Distance Along a Contour" beginning on page 4-42.

For information about the contours of the various geometric shapes, see Chapter 2, "Geometric Shapes," in this book.

To measure the length of a contour, use the GXGetShapeLength function, described on page 4-83.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help